feat: add live client OS detection and compatibility warnings - #20

The plugin page now tells a visitor whether an extension supports their machine before they try to install it. This matters most for tools like saturn-patcher, which ships Windows and Linux builds only and has no macOS or Linux arm64 binary.

What the visitor sees

The pill sits directly above the action buttons, so it is read before the install attempt rather than after a failed one.

Compatible — green border, subtle green glow:

┌─────────────────────────────────────────────────────────┐
│ ✅ Compatible with your system (Windows)                 │   emerald-500/40 border
└─────────────────────────────────────────────────────────┘   emerald-500/10 fill

Incompatible — amber warning, plus a deliberate opt-in download:

┌─────────────────────────────────────────────────────────┐
│ ⚠️  Not compatible with your current OS (macOS)          │   amber-500/40 border
│     Only available on: Windows, Linux                    │   amber-500/10 fill
└─────────────────────────────────────────────────────────┘

  Downloading anyway? Download anyway for another PC.

The download buttons are not disabled — a visitor can still fetch a build for another machine. The incompatible state just makes that choice explicit instead of accidental.

How it decides

                     ┌──────────────────────────┐
  request header ───▶│ detectOS(user-agent)      │──┐
                     └──────────────────────────┘  │
                                                    ├──▶ compatibilityFor(os, platforms)
                     ┌──────────────────────────┐  │      │
  navigator.userAgent│ detectOS(ua, touchPoints)│──┘      ├─▶ 'compatible'   → green
                     └──────────────────────────┘         ├─▶ 'incompatible' → amber
                                                          └─▶ 'unknown'      → render nothing

One pure implementation (src/lib/detectOS.ts) runs in both places, so the server and the browser can never disagree about what a User-Agent means.

Why there is also a client-side check

The server renders the pill from the request User-Agent, so it is correct on first paint. The browser then re-runs the same check and corrects it. The reason is iPadOS: since 13, an iPad reports a desktop Safari Macintosh User-Agent, and the only client-side tell is navigator.maxTouchPoints. A server-rendered pill would call an iPad "macOS" and, for a Windows/Linux-only plugin, miss the incompatibility entirely.

Zero layout shift

The server renders the pill in its final state, so the first paint is already correct. The client only ever toggles hidden on nodes that are always in the DOM — it never inserts or removes a node — so a correction cannot change the element's height. An unreadable User-Agent, or a plugin with no platform data, renders nothing rather than guessing.

Files

src/lib/detectOS.ts               +105   pure detectOS + compatibilityFor + supportedLabel
src/lib/compat-client.ts           +69   browser entry, corrects the pill
tests/detectOS.test.ts            +105   12 tests over the pure logic
tests/compat-client.test.ts       +163   4 tests over the DOM wiring
src/pages/plugin/[id].astro        +91   the pill, the download-anyway link
src/components/Icon.astro           +3   check-circle, alert-triangle

Verification

• Real browser, post-JS DOM — driven through headless Chromium with --user-agent per OS, asserting the final rendered state (not the pre-JS HTML):

  UA	state	icons	supported line	download-anyway
  Windows	compatible	✅ shown	hidden	hidden
  Linux	compatible	✅ shown	hidden	hidden
  macOS	incompatible	⚠️ shown	shown	shown
  Android	incompatible	⚠️ shown	shown	shown
  curl	unknown	none	hidden	hidden

• Tests — 83/83 pass (12 new for detection, 4 for the client wiring, including the iPadOS maxTouchPoints correction).

• Build — npm run build clean. tsc reports only the pre-existing astro.config.mjs vite-plugin duplicate error.

• Tailwind v4 — confirmed hidden, shrink-0, and the emerald/amber border/fill/text utilities are all emitted into the built CSS, so nothing depends on classes that JIT dropped.

One bug found while testing

Icon.astro only destructures name / class / strokeWidth, so the data-compat-icon attribute I first put on <Icon> was silently dropped and the client could not toggle the icons. Fixed by wrapping each icon in a <span> that carries the hook. Caught by diffing the post-JS DOM against the pre-JS HTML rather than trusting the server render alone.

This PR was created by an AI agent (OpenHands) on behalf of the user.

Summary by CodeRabbit

• New Features
  • Plugin pages now show whether a plugin is compatible with your operating system and list supported platforms when it isn’t.
  • When compatibility can’t be determined, the status panel is hidden. Downloads remain available, with a separate download-anyway option for incompatible platforms.